<html>
<head>
		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
		<title>The Equinox Runtime - Users Guide</title>
		<link rel="stylesheet" title="default" href="http://eclipse.org/default_style.css" type="text/css">
		<style>
			th,td { vertical-align:top; text-align=left}
			.issue { font-style:oblique; width:200px;}
			.box	{ background-color:#E0E0FF}
		</style>
</head>
	<body>
	<table BORDER=0 CELLSPACING=5 CELLPADDING=2 WIDTH="100%" >
			<tr> 
				<td ALIGN=left width="60%">
					
      <p><font class=indextop> eclipse</font><br>
        <font class=indexsub> runtime users guide</font> </p>
				</td>
				<td WIDTH="40%">&nbsp; </td>
			</tr>
	</table>

<blockquote> 
  <p><b>Summary</b> <br>
    This document details how to run and control the Eclipse 3.0 runtime. <br>
    Last Modified: 1700 March 23, 2004</p>
</blockquote>

<table border=0 cellspacing=0 cellpadding=2 width="100%" >
  <tr> 
    <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF"> 
      Controlling the runtime</font></b></td>
  </tr>
</table>
<p>This section has been moved to the Reference section of the ISV doc.</p>
<table border=0 cellspacing=0 cellpadding=2 width="100%" >
  <tr> 
    <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF"> 
      <a name="locations"></a>Locations</font></b></td>
  </tr>
</table>
<p>This section has been moved to the Reference section of the ISV doc.</p>
<table border=0 cellspacing=0 cellpadding=2 width="100%" >
  <tr>
    <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF"> Configurations</font></b></td>
  </tr>
</table>
<p>Configurations define a (sub)set of plugins found in an install. Users can
  then run a configuration on a data set (e.g., workspace). This is easy to see,
  for example, in a corporate setting where all of the Eclipse-based products
  might be installed and managed in one large install base. This install would
  contain potentially thousands of plugins. The Eclipse runtime scales to handle
  this but the resultant environment is likely not interesting for users. Such
  shared installations reduce the effort required to manage
  products as well as providing a centralized point for defining consistent
  sets of function.</p>
<p>For example,  users
    from, say, accounting should run the &quot;accounting configuration&quot; which identifies
  only those plugins useful to accountants. Similarly, the developers have their
  configurations as do the sales team. Further, products typically ship with
  predefined configuration(s) which define/suit their envisioned usecases. </p>
<p>When the Eclipse runtime is run, agents (plugins, remote entities or humans)
  can control the set of plugins that the runtime manages. Plugins managed by
  the runtime are candidates for execution. A candidate must be resolved before
  any of its code can be run or its presence (e.g., extensions) is made known.
  The runtime keeps track of the set of managed plugins and associated information
  in a configuration location. If there is no such location or the location is
  readonly, the runtime will still run but may not be able to offer all function.
  For example, it will not be able to remember between sessions which plugins
  it manages.</p>
<p>In a shared install the plugins themselves are shared as are the predefined
  configurations but each user may have their own area in which configuration
  values can be overridden and configuration-specific data can be stored. Eclipse
  uses the notion of <em>cascading configurations</em> to layer configurations.</p>
<p>freezing</p>
<p>&nbsp;</p>
<p>&nbsp;</p>
<p>To allow for shared installations and </p>
<p>&nbsp;</p>
<p>In </p>
<p>the notion of a <i>configuration area</i> (see <code>Platform.getConfigurationLocation()</code>).
  For the runtime, the configuration area contains a file called config.ini.
  This file, if present, contains a set of properties which control the construction
  and operation of the framework and runtime. For example, it is in this file
  that an initial set of bundles to load and start is defined.</p>
<p>The runtime does not define how this file is managed, nor does it contain
  any mechanism for updating the file (i.e., the runtime never writes the file).
  Rather, this responsibility is left to the entity managing the configuration.
  In some scenarios the configuration is defined and locked during product build,
  in other cases a system administrator crafts the configuration and pushes it
  to machines (or it is shared), in still other situations the end user manages
  the config.ini (in)directly using a configuration management tool such as the
  Eclipse Update Manager.</p>
<p>Any of these entities are free to put additional files and information in
  the configuration area. They should be careful however to consider cases where
  the configuration area is read-only. While it is not a requirement that plug-ins
  using the configuration area operate completely or partially when the area
  is read-only, your plug-in may not be usable in certain situations if it does
  not. For example, a typical tooling scenario includes a writable configuration
  area. If your plug-in is targetted at tooling environments, you are probably
  safe making that assumption. Note however that if somoene tries to use your
  plug-in in a constrained RCP scenario where there is no writable storage, they
  will likely be disappointed.</p>
<h4>cascading</h4>
<p>configurators</p>
<table border=0 cellspacing=0 cellpadding=2 width="100%" >
  <tr> 
    <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF"> 
      Running out of jars</font></b></td>
  </tr>
</table>
<p>running out of jars</p>
<table border=0 cellspacing=0 cellpadding=2 width="100%" >
  <tr> 
    <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF"> 
      The Console</font></b></td>
  </tr>
</table>
<p>using the console</p>
<table border=0 cellspacing=0 cellpadding=2 width="100%" >
  <tr> 
    <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF"> 
      Setting up your workspace</font></b></td>
  </tr>
</table>
<p>Users with existing workspaces should not encounter problems opening them with 
  the Equinox runtme. However, since the runtime plug-in structure has changed, 
  there some updating of classpaths may be required. In particular, developers 
  setting up a runtime workspace (i.e., a workspace containing plug-ins) will 
  need to either:</p>
<ul>
  <li>configure the target platform (Preferences-&gt;Plug-in Development-&gt;Target 
    Platform) to include the required plug-ins and then use PDE &quot;required 
    plugin&quot; classpath containers on their projects (recommended) or </li>
  <li>add projects (binary or source) for the required plug-ins and setup explicit 
    project dependencies for their projects</li>
</ul>
<p>Both of these can be accomplished using the PDE Tools-&gt;Update classpath 
  project context menu. </p>
<p>The following projects are needed (in addition to the normal set) :</p>
<ul>
  <li>org.eclipse.osgi</li>
  <li>org.eclipse.core.runtime.compatibility</li>
  <li>org.eclipse.update.configurator</li>
</ul>
<p>If you have an existing runtime workspace containing one of the following pre-existing 
  plug-ins, it must be updated to accurately match their new contents</p>
<ul>
  <li>org.eclipse.core.boot</li>
  <li>org.eclipse.core.runtime</li>
</ul>
<p>Note that these plug-ins are only required if your plug-in uses the old runtime 
  API. If you have adopted the new API (see <a href="#updating">Updating your 
  code</a>) then these projects/plug-ins are not needed.</p>
<p>There should be no need to modify the launch configurations as the runtime 
  is self-discovering.</p>
<table border=0 cellspacing=0 cellpadding=2 width="100%" >
  <tr> 
    <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF"> 
      Feedback</font></b></td>
  </tr>
</table>
<p> Should you encounter any problems while using the Equinox runtime, you are 
  encouraged to either log a bug report in the <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Equinox">Equinox 
  Bugzilla database</a> or make a posting to the Core <a href="http://dev.eclipse.org/mailman/listinfo/platform-core-dev">mailing 
  list</a> or the Platform <a href="news://news.eclipse.org/eclipse.platform">newsgroup</a>. 
</p>
</body>
</html>
